Character Script Commands

When the player enters the room, NPCs start performing the behavior you designate. There are four general classes of script commands, as follows:

1. Placement
2. Condition
3. Interaction
4. Queries
5. Decision making
6. Lighting

Notes about using NPC scripts
Imperatives
Behaviors
Function Primitives
Examples of branching code structures
Example of using the Special Command key
Example of using World Map commands
Predefined script vars
Threat clock display modes
List of player command input variables
Image Overlay commands

1.  Placement - Change the NPC's location.

1. Appear - If not visible, the NPC will appear at the current square (i.e. it enters the room). This command does nothing if the NPC is already visible. If a monster or the player occupies the square it is appearing in, then the NPC will wait until the square is vacant to appear.
2. Appear at - Use this to have an invisible NPC enter the room at a designated square different from the one where the NPC is current located. After selecting this command, the room will temporarily appear. Click on a square to select where the NPC will enter the room. This command does nothing if the NPC is already visible. If a monster or the player occupies the square the NPC is to appear in, it will wait until the square becomes vacant to appear.
3. Disappear - Removes the NPC from the room, making him invisible. Use this to show an NPC leaving the room. Script commands continue to play while the character is invisible but the NPC will not physically interact with any room elements unless it Appears again.
4. Move to - The NPC will move to the indicated square (selected by clicking on a room square, as above). Optionally, one of the entity types listed in the adjacent list box may be selected as who the NPC should follow. Hold <Ctrl> while clicking to select and unselect multiple selections. Each turn, the NPC will attempt to move one square closer to its destination. It moves roughly in a straight line and won't move on a given turn if something is in its way. Enable "Forbid turning" if you don't want the monster turning to face the direction it is moving each step. Hint: If you want the NPC to move in a more complex fashion, such as following a twisting corridor, this can be accomplished with a sequence of Move to commands, one to navigate each twist in the corridor. This command finishes when the NPC arrives at the destination square. Enable "Single step" to have the NPC only attempt to make a single step toward the indicated destination before continuing to the next script command. If no move can be made character will wait instead and the next script command will run on the next turn.
5. Move - Similar to Move to, except a relative number of tiles to move from the NPC's current location is specified. Positive numbers indicate movement south and east, and negative numbers are for moving north and west.
6. Face direction - Initially, the NPC faces the direction it is oriented when placed in the room. Use this command to turn the NPC in a different direction without moving (takes 1 turn).
7. Face towards like guard - Use this command to make the NPC change the direction they're facing towards a given point or entity just as the guard would.
   Single step: Setting this to on will make the character slowly turn towards the target direction. Off will make it turn immediately, just as face direction does.
   Targets: You can select zero, one or multiple targets from the list of entity groups - ctrl+click to deselect/select multiple. If no group is selected you will be asked to select a tile towards which the NPC should face.
   Using in conditions: This command can be used with if statements to check if the character is already facing the target direction.
8. Teleport to - Instantly moves the NPC to the indicated tile, as long as another entity is not occupying it.
9. Teleport player to - Instantly moves the player to the indicated tile processing all interactions: player will drown or fall into pit, potions will be drunk, the weapon will stab, pressure plates will toggle, etc.
   Interactions with potions: If the player is teleported multiple time during a single turn and they happen to land on one or more blocking potions (mimic, decoy and clone) then only the first of these potions will be consumed. However if the blocking potion is followed by non-blocking ones (invisiblity, speed, horns) they will be drunk. Horns are considered potions by the game. Avoid using this obscure mechanic in puzzles.
   Blocked teleports: This command will be silently ignored if you try to teleport the player: onto another monster/entity which can't be killed by stepping, to a location outside the room boundaries, onto the tile currently occupied by the player.
   Temporal recording: If the player gets teleported the quantum flux will reset and stop the temporal recording.
   Monsters on target tile: You can teleport onto a monster and instantly kill it if you are currently capable of killing that monster by stepping onto it. You can't teleport onto monsters that leave a pile behind, just like you can't step on them in the Slayer role or while wielding a dagger (in case of the dagger it's the stab that kills, you don't actually end up moving onto their space).
   

2.  Condition - How the NPC functions.

1. Set appearance - Changes the NPC's "Graphic" and default properties to the specified entity type.
2. Set movement type - Changes which tiles the NPC can move on. By default, an NPC with a movement type that would normally prevent it from moving over "ground" tiles can still move other these tiles. By using the Restricted Movement behavior, this can be prevented. The options are:
   1. Ground - Normal movement behavior. The NPC cannot cross tiles that block normal movement, including shallow water.
   2. Ground and Shallow Water - Like Ground, except that the NPC can wade in shallow water, and will not drown if dropped into shallow water.
   3. Water - The NPC can move over both types of water tile. Additionally, the NPC will not drown if dropped into water. If the NPC has the Restricted Movement behavior, the NPC cannot move over non-water tiles.
   4. Wall - The NPC can move through wall and doors tiles. If the NPC has the Restricted Movement behavior, the NPC cannot move over any other tiles.
   5. Air - The NPC can move over all non-wall and non-door tiles. Additionally, it is not damaged by Hot Tiles or Floor Spikes, and cannot be killed by being dropped into water or into pits.
   Changing an NPC's appearance with Set appearance will change the movement type to that appearance's default movement type unless the Keep Behaviors option is set to on.
3. Turn into monster - Turns the NPC into a regular monster of the type indicated by its graphic. This ends script execution immediately and the NPC is permanently replaced by a regular monster.
4. Imperative - Sets a special status condition on the NPC (see Imperatives). Compatible imperatives may be combined.
5. Behavior - Turn various NPC interactions on and off. Some appearances have behaviors set by default. Behaviors may be combined. (see Behaviors).
6. Replace with Default Script - If the NPC is a custom NPC type, replaces the script content with that NPC type's default script. That script will then begin executing. Has no effect when used in an NPC with a pre-defined type, or if a default script is already being run.

3.  Interaction - How the NPC interacts with its environment.

1. Add room to map - Adds the chosen room to the player's map, as if they had explored. This exploration is not removed by undoing moves or restarting the room.
2. Activate item at - Activates the item at the room square you select. Items that can be activated are: orbs, pressure plates, lights and wall lights. Nothing will happen this turn if no relevant item is at the indicated square. Hint: Move the character next to orbs before striking them for more intuitive behavior. If no one is next to the orb when struck, it will appear that Beethro is using his portable orb.
3. Speech - Causes someone in the room to say something.
   Dialog text: Type the words that are said. This may be left blank in order to only play a sound effect.
   Speaker: who says the words. The text appears next to the person's figure in the room and their face appears on screen while they are speaking. Use "Custom" to have the NPC "throw its voice" to a different square in the room. If a monster or character is located at the indicated square when this command is executed, it will appear as if this monster or character is speaking. If speaker is set to "None", or the person indicated is not present in the room, then the words will appear next to the NPC.
   Mood: the face displays the indicated mood. Not all moods are available for all speaker types.
   Speech delay: How long, in milliseconds, the speech lasts for. If placing multiple lines of speech in sequence, this determines how much time passes until the next line of speech (and corresponding speaker) is displayed. Set this value to zero to have the game engine calculate how long to wait based on the length of the speech text.
   Add sound: A sound file (Wave or Ogg Vorbis format) on disk can be optionally attached to the speech. If a sound is specified, it will play along with the text and the next speech command will be played when the sound completes. Use a non-zero speech delay to force when the next line of speech will play regardless of how long the attached sound file plays.
   Exporting speech text: A hold's entire speech script can be exported to an HTML file on disk when exporting the hold by adding the line "ExportSpeech=1" to the "[Startup]" section of Data/drod.ini.
4. Flush Speech (on/off) - Tells the game to immediately process any previously queued speech that hasn't had time to play yet. If "On" is selected, these texts will appear immediately onscreen. If "Off" is selected, then text that hasn't played yet won't show at all. Hint: This command is used for dramatic effect, to ensure speech queued after this command will be immediately spoken, as intended. This command is not needed if it doesn't matter at what point in play speech texts are delivered.
5. Ambient sound - Plays a custom sound effect, imported from a sound file on disk. Select "Loop Off" to play the sound once, and "Loop On" to play the sound repeatedly. Selecting no sound file in conjunction with this command will silence any ambient sounds playing when the command is executed.
6. Ambient sound at - Plays a custom sound effect, imported from a sound file on disk, from the room location you specify. The sound will play from the direction the sound is coming to the player in the room and will be quieter the further the player is away from that room tile. Selecting no sound file in conjunction with this command will silence any ambient sounds currently playing at the room location you specify.
7. Build marker - Mark a region of the room for building a certain object by citizen builders. When a builder builds on a tile, the tile is unmarked. Each room tile can be marked only by a single object type at a time. Selecting "None" unmarks any existing build markers in the room region you specify.
8. Build - Instantly build the indicated object in the specified room region. You may also remove objects from the specified room layer.
9. Link Orb - Connects an orb or pressure plate to a yellow door, arrow or fire trap. Existing connections between the target objects will be overwritten. The None option can be used to completely remove the orb connection between two objects.
10. Destroy trapdoor - Causes a trapdoor at the indicated location to drop down.
11. Go to level entrance - Sends the player immediately to any level entrance defined in the hold, or ends the hold.
12. Attack tile - Executes an attack of the designed damage or stun type to the designated tile.
13. Push tile - Executes an push in the designed direction type on the designated tile.
14. Play video - Plays a video file, imported from a video file on disk, at the specified screen coordinates. Sound tracks in video files are not supported, but sounds and music may be played concurrently with the proper script commands. Currently, only Ogg Theora video format is supported.
15. Set music - Set any of the available music themes to play. Additionally, custom music, imported from a music file on disk, may be played. Only Ogg Vorbis and Wave formats are supported. Custom music can be set to continue playing across rooms by executing this command on room entrance.
16. Player role - Indefinitely sets the player to play the role you indicate. In these roles, properties that apply to that entity type generally hold.
17. Set player behavior - Indefinitely sets a specified player behavior to use the specified control state. The following states can be set:
    • Default - The behavoir functions based on the active player role.
    • On - The behavoir is always active.
    • Off - The behavoir is disabled.
    • Powered - The behavoir is disabled until a power token is activated.
    • Unpowered - The behavoir is active until a power token is activated, at which point it is disabled.
18. Set player state - Sets a specified player state on or off. This lasts until the player interacts with another element that changes that state, or until they leave the room.
19. Set player stealth - Change the player's stealth property on room entrance to the indicated value indefinitely.
20. Set player weapon - Change the player's current weapon type, or enable or disable wielding a weapon indefinitely.
21. Set entity weapon - Change the weapon of the armed monster or player at the specified position. Unlike Set player weapon, this change does not persist between rooms.
22. Cut scene - When set, room turns will proceed automatically at the rate you specify without player intervention. Invoke this command with a rate of "0" to end the cut scene and return movement control to the player. Hint: This command is used for dramatic effect, to have NPCs do things, such as move around the room, without requiring the player to take turns to allow the NPCs to likewise move. If on a given turn no NPCs are executing, the cut scene playing will automatically terminate, restoring control to the player.
23. Answer option - Provides a multiple choice option for a Question command (see below). A label from the list of defined Label commands in the script must be selected as the point from where the script will continue execution if the user selects this choice. Up to nine answer options are supported for a given Question. Any additional options are ignored.
24. Set var - Each hold you create contains a set of zero or more variables, named by you. Use these variables to track persistent game state information across rooms during play. To add a variable to a hold, type its name into the uppermost text box and click "Add".
    Syntax: Variable names must begin with a letter, period, hash (#) or at symbol and not contain any punctuation except underscore ('_'). Starting a variable name with a period ('.') configures it as a local variable instead of a global. This means each NPC will have its own version of a variable with this name and there is no value sharing among them.
    Arrays: Starting a variable name with a hash (#) or at symbol (@) configures it as an array variable. See Script arrays for more information.
    Modifying variables: Select a hold variable from the list, choose an operation and a value. Variables may either store an integer or text. If the operation you specify is "Assign text" or "Add text", the variable you select will be set to store the text you provide. You may also reference other variables to insert into the given text. For operations dealing with numbers, if you provide the name of another variable, its value will be used (invalid names will be considered a value of 0). Otherwise, the number you provide is used. Use the text box on top to specify the text being assigned or added to the variable. For other operations, use the text box on the right to input a number or variable name. The variable will store a number.
    Using variables in text: In variable text assignments, Speech, Questions (see below), level entrance texts, and scroll text, type "$<var name>$" to insert the current value of the variable you name at this point in the text. Type "$\n$" to skip to the next line of text.
    Comprehensive variable reference list: In the Room Editor Screen, press F2 to output a comprehensive list of hold variables to the clipboard (use the paste option of your favorite text editor to view this text). This list shows all rooms and NPC (x,y) locations where the variable is referenced in a script throughout the hold. A number after the (x,y) location of the script indicates how many times the variable is referenced in that script.
    Monitoring variables during play: Press Ctrl-F7 while playing to turn on and off the variable monitor. Whenever a script changes a hold variable, you will be notified onscreen. This only works while playtesting, playing a hold you authored, or playing a CaravelNet hold in beta.
    Deleting variables: To permanently remove a hold variable, select it from the list box on the left and click "Remove". Note that this removes the variable completely from the hold and all NPC scripts that use it, not just from this particular script.
    
25. Set var at - Allows the Set var command to be invoked with an NPC on another tile. All assignment and parsing will occur as if the target NPC called the Set var command. Thus, its local variables will be used, allowing them to be written or read remotely. This command can also be used an If condition. The condition is satisfied if the command successfully invokes a variable assignment on an NPC in the target square. Hint: Use this for scripts that rely on the result of a remote variable assignment.
26. Reset _MyScript variables - Sets the value of all _MyScript variables to -9999, so they no longer override command values.
27. Set shallow water traversal - Sets how and under what conditions the player interacts with shallow water terrain.
28. Game effect - Display a visual effect at a specified room location. Particle effects may have a direction given them. Some effects may play an optional accompanying sound effect.
29. Image overlay - Input a custom set of commands for displaying a custom image effect in the game room.
30. Generate entity - Creates a new entity of the specified type at room location (x,y) and the indicated orientation once that room tile is vacant. Custom NPCs with a default script defined may be created where an entity already occupies the room tile, but begins as not visible. NPCs will begin executing their default script when created.
31. Start global script - Begin executing the specified NPC's default script. To use this command, first create a custom NPC role, then give it a default script. The global script will automatically run in each room you enter for the rest of the campaign, until an End command or variant is executed. Only one instance of each custom NPC may be run as a global script while in any given room.
32. Display filter - Display the room with the indicated graphic filter.
33. Flashing message - Flash a message onto the room area. By default, the text is displayed in bright yellow. You may specify an alternate color by providing a six-character RGB hexadecimal code, with each two-character pair indicating a color value between 0 and 255.
34. Challenge - Used for the CaravelNet achievement/trophy system. When executed, this indicates that a challenge with the given name has been completed by the player.
35. World Map Select - Select an overworld map for subsequent World Map commands to be performed with reference to. Without this command, the other World Map commands will do nothing.
36. World Map Music - Sets the music that plays on the previously selected map. This only need be executed once during a hold playthrough. Any subsequent executions will override the previous setting.
37. World Map Tile Icon - Places an icon on the previously selected map. You specify the position the icon appears on the map, its state, and if active, what level entrance or map it leads to when the player clicks on it from this map screen. Icons persist on the specified map from that moment for the entire playthrough. Placing an icon at the same position as another will override the first. Using icon type "Off" will remove an icon from the map. You can select a custom NPC with a looping animation speed in order to display an animated graphic on the map.
38. World Map Image Icon - Places an image on the previously selected map. Works in other respects as the "World Map Tile Icon" command.

4.  Queries - Use queries to examine the state of the room and wait indefinitely until certain events occur.

1. Question - If one or more Answer option commands have been provided previously in script execution, this will ask the user a multiple choice question with the dialogue you specify and answer options previously provided. Script execution will continue from the label of the Answer option selected by the player. Once a Question has been asked, the list of Answer options is reset for the next Question.
   If no Answer option commands have been provided before this command is executed, the user will be asked a "Yes" or "No" question with the dialogue you specify. If a yes/no Question is executed as the condition for an If ... command, the corresponding script block will execute if the user answers "Yes".
2. Select square - Causes the next game move to become a position input, as if the player had stepped on a potion. The selected position is placed into the _ReturnX and _ReturnY variables. The selection can be configured to allow any room tile to be chosen, or to use the same restriction as double potions. If the player has consumed a potion, this command will be delayed until the next full turn has processed.
3. Wait - This tells the NPC to do nothing until the number of game turns you specify has passed. Wait 0 will stop the script at the current point until the next turn.
4. Wait for event - The NPC waits until the specified game event has taken place. If the event has not taken place, and the command is not being used as a condition for an If command, another check will be performed at the end of the turn, and the script will continue on the next turn if the specified event has taken place. This also occurs if it is in a multi-expression wait. In this case, be aware that other conditions may have changed between the intial check and end-of-turn check.
5. Wait for entity - The NPC waits for any of the selected entity type (or entities) to enter the room region you specify. Hold <Ctrl> while clicking to select and unselect multiple selections. After selecting this command, the room will temporarily appear. Hold down the mouse button and drag the mouse cursor to select the area any of the entity or entities must enter before the NPC does anything else.
6. Wait while entity - Wait while any of the selected entity type remains in the room region that you select.
7. Wait for door to (open/close) - Waits for the door at the selected room square to either open or close.
8. Wait for turn - The NPC does nothing until at least the specified number of game turns has passed since the player entered the room.
9. Wait for clean room - Waits until the room is in a conquer-ready state (i.e. all kill-required monsters have been removed).
10. Wait for clean level - Waits until the level has been cleared (i.e. all required rooms have been cleared).
11. Wait for Entity Type - Wait for a specific entity type to be present in a specified room region.
12. Wait while Entity Type - Wait while a specific entity type is present in a specified room region.
13. Wait for monster remains - Wait for the remains of a specific entity type to be present in a specified room region.
14. Wait for open move - Wait until it becomes possible for the NPC to move in the specified direction.
15. Wait for open tile - Wait until the tile at the specified location is open, according to the specified movement type. Additionally, this command can be configured to ignore tile-blocking weapons and entities. Hold <Ctrl> while clicking to select and unselect multiple selections for ignorable entities.
16. Wait for player state - Waits until the player has a specific state (or doesn't have it if set to Off).
17. Wait for player to face - Waits until the player turns in the specified direction.
18. Wait for player to input - Waits until the player inputs the specified command.
19. Wait for player to move - Waits until the player moves in the specified direction.
20. Wait for player to touch me - Waits until the player bumps into the NPC.
21. Wait for building markers - Waits until script-defined building markers exist in the room region you specify.
22. Wait for no building markers - Waits until no script-defined building markers exist in the room region you specify.
23. Wait for build marker type - Waits for the specified type of building markers are placed in the room region you specify.
24. Wait while build marker type - Waits until none of the specified type of building markers exist in the room region you specify
25. Wait until var - Waits until a hold variable meets the condition you specify.
26. Wait until expression - Waits until a given expression satisfies the condition you specify. In addition to hold variables, expressions can also use function primitives. Expressions can only be compared to constant values.
27. Wait for Weapon - Waits until a weapon is in the specified specified room region. By default, this command checks for any weapon, but specific weapons can be waited for instead. Hold <Ctrl> while clicking to select and unselect multiple selections. The NPC will not detect its own weapon with this command.
28. Wait for item - Wait until the specified element is located in the marked room region.
29. Wait for item group - Wait until any element from the specified group is located in the marked room region.
30. Wait while item group - Wait until no elements from the specified group are located in the marked room region.
31. Wait for brain sensing player - Wait until a brain can detect the player.
32. Multi-expression Waits - Multi-expression wait commands are used to perform an atomic check on multiple conditions, i.e., as a single combined boolean query, which returns a single true or false value. Script execution halts at this point until the multiple conditions are met as specified. The expression block begins with Wait for All, Wait for Any or Wait for Exactly One command, and should end with a Wait for Conditions End command. An All block will wait until all subqueries are true, an Any block will wait until any subquery is true, a None block will wait until not subquery is true, and an Exactly One block will wait until exactly one subquery is true. Additionally, a multi-expression wait block can be used as a condition for an if statement. Multi-expression wait blocks can be nested if more complex logic is required. All "Wait for" commands can be used as subqueries, along with the Set role, Set player weapon, Face towards like guard and Set movement type commands, which function as they do when used as an if condition.
33. Get natural target - Finds the position of the entity this character would target if it was a monster and stores it in two global variables, _ReturnX and _ReturnY.
    Targeting type: You can chose what type of targeting to use when finding the target.
    
    • Regular monster: This is the targeting used by unbrained roaches, goblins, etc.
    • Brained monster: Finds the adjacent tile a brained monster would move to. This targeting type will consider decoys, and if the player is hidden or not a target, leading to a non-brained move when appropriate. If a non-brain move is made, it will be chosen based on the monster's beelining imperative.
    • Best brain tile: Finds the adjacent tile with the best "brain score". This will always path to the player unless there is no path to the player, it which case it will not find a target. A monster with direct-only beelining may choose a tile blocked by a brain-invisible obstacle.
    • Best brain direction: Finds the direction to the adjacent tile with the best "brain score". _ReturnX will contain the best open direction, and _ReturnY will contain the best direction when not considering brain-invisible obstacles. If there is no path, it will return a value of 4 to both return values. A monster with direct-only beelining may choose a direction blocked by a brain-invisible obstacle.
    • Nearest open room edge to me: Finds the closest room tile on the edge of the room that has a path to the NPC, using the same rules as horns. A variant of this target type is also provided for finding the closest edge tile to the player.
    Results: Results from this function are stored in _ReturnX and _ReturnY which are global variables, accessible by all scripts.
    No target: If no target is found the character's current position will be returned.
    Using in conditions: This command cannot be used with an if statements.
    
34. Get entity direction - Gets the direction an entity at a given position is facing and stores the result in _ReturnX.
    Direction values: NW=0, N=1, NE=2, W=3, No orientation=4, E=5, SW=6, S=7, SE=8.
    Results: Result from this function is stored in _ReturnX which is a global variables, accessible by all scripts.
    No target: If no entity is found the function returns No orientation. If player is found on the specified position, the player's direction is returned.
    Using in conditions: This command cannot be used with an if statements.
    
35. Count entity type - Counts the number of the given entity type in the specified room region, and stores the result in _ReturnX.
36. Count item - Counts the number of the given game element in the specified room region, and stores the result in _ReturnX.

5.  Decision making - Use the following commands to execute only a marked portion of script commands or to continue executing script commands from a different location in the script.

1. If ... - Use this command to optionally run a block of one or more script commands, based on a condition you specify in the next script command, which must be a query. If the query is immediately satisfied, then the script commands that follow after will be executed. An If End, Else or Else if command indicates the end of the optional code block. If the following query is not true, the script will continue after the following the next Else or If End command that marks the end of the optional code block.
2. If .... The end of the Else block is indicated with an If End command.
3. Else - Marks the beginning of a script section that is executed if the query condition following the If ... command is not satisfied. Else commands in conditional blocks are optional, but they must always follow somewhere after an If ... to be meaningful.
4. Else if can optionally be used instead of Else to avoid nesting script commands. It works exactly the same as nesting an If ... If End block inside an Else
5. If Not ... works as a logically reversed If ..., such that the commands within the code block will run if the given query is not satisfied.
6. If End - Marks the end of If ... and Else blocks.
   Notes:
   1. A "?" symbol displayed in front of a command in the script list means the command is not a recognized as a valid condition for an If ... command.
   2. If ... commands may be nested, i.e., an inner code block may be completely contained within an outer code block.
   3. A "!" symbol displayed in front of a command in the script list means that an If ... or Else block is not properly closed with an If End command at the end, or that an Else command is placed without an If ... coming first.
   4. See "Examples of branching code structures" below.
7. Label - marks a location in the script to continue executing commands from (used in conjunction with Go to and Answer option commands). Also, labels may be used to simply comment in normal language on what the following script commands do.
   Labels can also be used as comments if you prefix them with a double slash. Eg: "// This is a comment" will display differently in the command list and will not appear in any command that allows jumping to a label.
8. Go to - Select a label to continue executing commands from. Hint: Use "Go to" to make a loop in the script that repeats a sequence of commands over and over. Use a Wait 0 command as the last statement of a loop that is to be executed once each turn.
9. Gosub - Similar to "Go to", it continues execution from the indicated label. Used in conjunction with "Return" for more modular scripting.
10. Return - Continue executing commands from the most recent "Gosub" command executed. When multiple Gosub commands are executed, then multiple Return commands will jump back to these in order from most to least recent.
11. End on room exit - Removes the NPC for the rest of the current game once the player exits the room. If the room is restarted before exit, then the NPC script will begin executing again from the beginning. Hint: use this command to have the NPC continue executing commands.
12. End - Ends the character script immediately and will remove the NPC for the rest of the current game once the player exits the room. If the room is restarted before exit, then the NPC script will begin executing again from the beginning. Hint: use this command to stop the NPC from executing any more commands.

6.  Lighting - The following commands can be used to alter the lighting layer of a room. Only one type of lighting can be present on a tile, so these commands will overwrite pre-existing tile lighting. Architects should be considerate to players, and not excessively change the lighting of a room during play.

1. Set ceiling darkness - Adds darkness to an area. Values between 1 and 32 inclusive will darken a tile, while a value of zero will remove lighting from the tile. Values outside of this range will be clamped to the valid range.
2. Set ceiling light - Adds colored light to an area. Any of the 16 predefined colors can be used. Selecting 'none' will remove lighting from the tile.
3. Set wall light - Adds a wall light element to a tile, with the given intensity. Any of the 16 predefined colors can be used, with an intensity between 1 and 8 inclusive. Selecting 'none' or setting an intensity of zero will remove lighting from the tile.

Notes about using NPC scripts

1. Each character script begins execution when the room is entered. Once a script runs to completion, the character stops functioning. If the NPC is still in the room when the script ends, it will remain where it is until the player exits the room. Upon reentry, the script will start again from the beginning.
2. NPCs are not used to determine room completion (conquer status). That is, NPCs with un-Ended scripts will continue to appear in a conquered room each time the player reenters it.
3. A script can be made to not start again when the player reenters the room by placing an End command at the end of the script or by executing an End on room exit command anywhere within the script. A character can be made to run only while the room is unconquered by placing an If <Wait for Clean Room> check at the beginning of the script and If End at the end.
4. An NPC can be turned into a regular monster with the Turn into monster command. In this case, it may need to be killed in order to conquer the room.

Imperatives - NPC/script properties that may be set with the Imperative command.

• Vulnerable: Makes the NPC vulnerable to killing. This is the default setting for most NPC graphic types.
• Invulnerable: Makes the NPC invincible so it cannot be killed by stabbing or other methods of inflicting damage. The NPC may still be killed by falling off a platform or by briar growth. Some NPC types, like Wubbas, are invulnerable by default.
• Critical hero: When set, the room will restart if the NPC is ever killed. Some NPC types, like Beethro and Halph, are marked critical heros by default.
• Required target: When set, the NPC must be killed in order to conquer the room. This command only applies when the room is not otherwise clean on entrance.
• Safe: Forbids the NPC to step on the player and kill him (default).
• Sword safe to player: Sword stabs from this NPC won't harm the player.
• Deadly: Allows the NPC to step on the player and kill him. Also makes sword hits deadly to the player (default).
• Friendly: Marks the NPC as "friendly". Killing it will not break stealth, and Stalwarts and Soldiers will avoid stabbing the NPC. An NPC that is set as Safe is automatically set to be friendly.
• Unfriendly: Marks the NPC as "unfriendly". Killing it will break stealth, and Stalwarts and Soldiers may stab the NPC. An NPC that is set as Deadly is automatically set to be unfriendly.
• Die: Makes the NPC die with a blood splatter.
• Die special: Makes the NPC perform a monster-specific death sequence, if applicable. Currently, this command applies to rock golems and fegundos. Rock golem NPCs will turn into a rock pile when this command is invoked. Fegundos will explode and turn into a regular fegundo ash monster. For other monster types, this acts identically to "Die".
• End when killed: If the NPC is killed, mark the script as ended so it doesn't repeat when the room is reentered.
• Direct-only beelining: When desired diagonal movement is blocked, then don't move at all.
• Normal beelining: Move diagonally when desired and possible, otherwise move axially if possible, prefering vertical movement when both horizontal and vertical movements are open.
• Smart beelining: In addition to Normal beelining behavior, when a desired diagonal movement is blocked, choose the better of horizontal or vertical movement that will get closer to the destination (default).
• Smart beelining: As flexible beelining, but also will move diagonally closer to the destination when a desired axial move is blocked.
• Pathfinding (open only): The shortest path is calculated and taken to the destination. Whenever the currently calculated path becomes blocked, then a new shortest path is calculated. When no open path is found, no movement is made.
• Pathfinding: The most intelligent movement option. The shortest path is calculated and taken to the destination. Whenever the currently calculated path becomes blocked, then a new shortest path is calculated. When no open path is found to the destination, then the path that has the fewest obstacles along the way is followed, defaulting to normal beelining whenever obstacles completely block the remaining path.
• Brain pathmap obstacle: This NPC is perceived as an obstacle to brain pathmaps, and brained pathmaps will calculate paths around the NPC.
• Not brain pathmap obstacle: This NPC is not perceived as an obstacle to brain pathmaps (default), and brained pathmaps will not calculate paths around the NPC.
• NPC pathmap obstacle: This NPC is perceived as an obstacle to other NPCs using the Pathfinding imperative. Other NPC pathmaps will be calculated around this NPC.
• Not NPC pathmap obstacle: This NPC is not perceived as an obstacle to other NPCs using the Pathfinding imperative. Other NPC pathmaps will not be calculated around this NPC.
• Ghost display: When invisible this character will still be drawn to the screen. It will be drawn before (underneath) visible entities.
• Ghost display overhead: Just like Ghost display above, except the NPC will be drawn over other characters and monsters.
• No ghost display: Disables any previously activated Ghost display on this NPC.
• Invisible inspectable: This NPC will be included in the tile description when right-clicking on its tile even when it is invisible (Ghost Display is treated as invisible).
• Invisible not inspectable: This NPC will not be included in the tile description when right-clicking on its tile when it is invisible.
• Invisible includes move order: Even when invisible (Ghost Display is still invisible) this NPC will be counted for the purpose of determining movement order. Additionally, if Invisible inspectable imperative is set, the movement order of this character will also be visible.
• Invisible don't include move order: Reverses the above to original behavior - this NPC when invisible will not be included when counting movement order and if it's inspectable the movement order will not be displayed when right clicking on its tile.
• Not pushable: Makes this NPC resistant to any kind of pushing, even with weapons which naturally allow pushing (eg. staff).
• Default pushable behavior: Resets the pushability of the NPC to the default behavior.
• Pushable by body: Makes the NPC pushable by the body of the player, mimics, constructs and characters with the Push Monsters behavior. Regular, non-NPC guards, stalwarts, slayers and soldiers can't push mirrors and thus won't be able to push an NPC with this imperative. The same goes for all monsters except constructs which can push mirrors.
• Pushable by weapon: Makes the NPC pushable by any weapon effectively making it invulnerable to weapon attacks. It won't be able to push the NPC wielding dagger because dagger doesn't occupy a physical space. All other forms of attack still kill the NPC, including adders eating them, explosions, spike and fire traps.
• Stunnable: Weapon pushes will stun this NPC.
• Not stunnable: Weapon pushes will not stun this NPC, but it will not move on the turn it was pushed (unless it was pushed after it already moved).

Behaviors - Player and NPC properties that may be turned on and off with the Set player behavior and Behavior command. In most cases, the Invulnerable imperative takes precedent over damage immunity behaviors. Some NPC types will have behaviors set by default. Changing an NPC's appearance with Set appearance will reset behaviors to that appearance's default behaviors unless the Keep Behaviors option is set to on.

Shared Behaviors:

1. Light Fuses: The entity can light fuse ends by stepping onto them.
2. Drops Trapdoors: The entity will drop trapdoors and melt thin ice.
3. Drop Trapdoors When Armed: The entity will drop trapdoors if it is armed with a weapon, and will melt thin ice.
4. Push Objects: The entity can push objects such as Mirrors and Powder Kegs.
5. Push Monsters: The entity can push monsters that can be pushed. Currently, only NPCs with Pushable by body can be pushed in this manner.
6. Move Platforms and Rafts: The entity can push platforms and rafts by moving against their sides.
7. Use Tunnels: The entity will use tunnels when moving in the appropriate direction, and will consider moves through a tunnel to be open.
8. Puff Target: Puffs will treat the entity as a target. This does not affect the entity's vulnerability to puffs.
9. Weapon Damage Immunity: Attacks from the specified weapon will not kill the entity. The weapon can still be used to push the entity when applicable.
10. Floor Spikes Immunity: The entity cannot be killed by spike traps. Flying entities will ignore the state of this behavior, and are always immune to spike traps.
11. Fire Trap Immunity: The entity will not be killed due to ending the turn on an active fire trap.
12. Hot Tile Immunity: The entity will not be killed due to staying on a hot tile for more than a turn. Flying entities will ignore the state of this behavior, and are always immune to hot tiles.
13. Explosion Immunity: The entity cannot be killed by explosions, including ones from the Attack Tile command.
14. Adder Immunity: Adders cannot eat the entity.
15. Puff Immunity: The entity cannot be killed by puffs, either from Puffs moving onto them, or due to the entity moving onto a Puff. This does not affect whether the entity attracts Puffs.
16. Push to Fall Immunity: The entity cannot be pushed onto pit or water tiles if this would kill them. The entity can still be pushed into other potentially dangerous tiles, such as active fire traps.

Player Behaviors:

1. Body Strike Orbs/Beacons: The player can activate orbs and toggle seeding beacoms by bumping them.
2. Step Kill: The player can kill monsters by stepping onto them.
3. Has Weapon: Allows the player to weild a weapon. The weapon can still be disabled by room elements, or with the Set player weapon command.
4. Use Potion/Blow Horn: The player can use the specified potion type. They will also gain the ability to move onto that type of item if their role would otherwise prevent its.
5. Face Movement Direction: The player will turn to face the direction of their movement, even if they have a weapon that would prevent it. When this behavior is disabled, the player will always retain their direction when moving, even when unarmed. Rotation moves are not effected by this behavior.
6. Body Attack Immunity: Monsters cannot move onto and kill the player. This does not affect whether an Adder can eat the player.

NPC Behaviors:

1. Activate Tokens: The NPC will activate architectural tokens when it moves onto them, except for Temporal Split Points.
2. Activate Pressure Plates: The NPC will press pressure plates when it moves onto them, and will hold down pressure plates while on them.
3. Avoid Firetraps: The NPC will treat active firetraps as a movement obstacle. The NPC can still be pushed into an active firetrap.
4. Avoid Puffs: The NPC will treat Puffs like other monsters, and consider them movement obstacles. The NPC can still be pushed into a Puff.
5. Restricted Movement: The NPC can only move onto tiles it's movement type would normally allow movement onto. See Set movement type for details.
6. Instant Movement: Script execution for the turn will not halt after a Face direction or Face towards like guard command, or after a Move or Move to command in Single step mode. Move and Move to commands that are not single step will still halt execution.
7. Only Process On Full Turns: The script will not run during "half-turns" when the player is under the effect of a speed potion.
8. Can Appear On Weapons: The NPC can appear on a square occupied by a weapon when using the Appear or Appear at commands.
9. Can Kill Non-target Player: The NPC will be able to step onto and kill the player even if the player isn't a monster target.
10. Can Be Attacked By Monsters: Hostile monsters can move onto and kill the NPC. Monster attacks ignore the Invulnerable imperative. Additionally, this does not affect whether an Adder can eat the NPC.
11. Monster Target: Monsters other than Puffs will treat the NPC as a target. This does not affect the NPC's vulnerability to monsters.
12. Monster Target When Player Is Target: Monsters other than Puffs will treat the NPC as a target as long as the player is a monster target. Otherwise, monsters will ignore this character. This does not affect the NPC's vulnerability to monsters.
13. Ally Target: Stalwarts and Soldiers will treat the NPC as a target. However, they will avoid stabbing the NPC if it is Friendly.
14. Wakes Evil Eyes: An evil eye will wake up if it sees the NPC.
15. Wakes Evil Eyes When Monster Target: An evil eye will wake up if it sees the NPC if the NPC is a monster target.
16. Briar Immunity: Briar cannot grow onto and kill the NPC.

Function primitives - Predefined functions may be inserted anywhere a variable is referenced. The function will return a value based on the input parameters and current game context, where applicable. Functions are useful to apply in variable expressions. All inputs must either be integer values or an expression that resolves to an integer value. All outputs are likewise integers. Function names are case-insensitive.

* _abs(x) - Returns the absolute value of x

* _min(x,y) - Returns the lesser of two values

* _max(x,y) - Returns the greater of two values

* _orient(dx,dy) - Returns an orientation id (0-8), given x,y directional offsets

* _facing(dx,dy) - Returns the orientation id (0-8) most directly facing in the direction of the given x,y vector

* _ox(o) - Given an orientation id (0-8), returns its x component offset (-1, 0, 1). Given an invalid orientation value, the same value is returned.

* _oy(o) - Given an orientation id (0-8), returns its y component offset (-1, 0, 1). Given an invalid orientation value, the same value is returned.

* _rotateCW(o) - Given an orientation id (0-8), returns the id of the orientation in a clockwise direction. Given an invalid orientation value, the same value is returned.

* _rotateCCW(o) - Given an orientation id (0-8), returns the id of the orientation in a counter-clockwise direction. Given an invalid orientation value, the same value is returned.

* _rotateDist(o1, o2) - Give two orientation ids (0-8), returns the number of rotations between them. If either value is invalid, or has a value of 4, returns a value of zero.

* _dist0(x1,y1,x2,y2) - Returns the L-infinity norm (max axial distance) between two 2-D coordinates.

* _dist1(x1,y1,x2,y2) - Returns the L-1 norm (Manhattan distance) between two 2-D coordinates.

* _dist2(x1,y1,x2,y2) - Returns the L-2 norm (Euclidean distance) between two 2-D coordinates.

* _ArrowDir(x,y) - Returns the the orientation id (0-8) for the arrow at the room location (x,y). If no arrow is present, returns a value of 4.

* _RoomTile(x,y,z) - Returns the numeric id of the room tile at (x,y). Use the z parameter to select the tile layer.
Supported layer values - 0 -> O Layer, 1 -> F Layer, 2 -> T Layer
Hint: Each layer corresponds to a tab in the editor's tile selection dialog.

* _MonsterType(x,y) - Returns the numeric monster type of the monster at (x,y). If no monster is present on the tile, -1 is returned.
Hint: This can be used to compare the monsters in different tiles, or for providing a value for _MyScript injection.

* _CharacterType(x,y) - Returns the logical type of the scripted character at (x,y). If no character is present on the tile, -1 is returned.
Hint: This can be used to provide a value for _MyScript injection.

* _MonsterSize(x,y) - Returns the number of tiles occupied by the monster at (x,y). If no monster is present on the tile, 0 is returned.

* _EntityWeapon(x,y) - Returns the numeric weapon type of the monster or player at (x,y). The weapon type will be returned even if the entity is currently disarmed. If no weapon-using entity is present, -1 is returned.

* _BrainScore(x,y,t) - Returns the distance the given tile is from the player, along a brained path, for the given movement type. Tiles that cannot access the player return a value of -1.

* _BrainDist(x1,y1,x2,y2,t) - Returns the distance between the two tiles along a brained path, using (x1,y1) as the destination, for the given movement type. If no such path from (x2,y2) to (x1,y1) exists, returns a value of -1.

*_CleanRooms(f) - Returns how many rooms the player has cleared on the current level. It takes a bit map flag as an argument. A value of 1 counts required rooms, 2 counts secret rooms, and 4 counts unrequired rooms. These values can be combined to count multiple categories.

Examples of branching code structures:

1. A single code branch:
   If ...
         <condition>
      some optional commands here
   If End
2. Two code branches:
   If ...
         <condition>
      some commands here
   Else
      some other commands here
   If End
3. Nested branches:
   If ...
         <condition>
      some commands here
      If ...
            <condition>
         some more commands here
      If End
      some different commands here
   If End

Example of using the Special Command key

Example of using World Map commands

When a player moves close to a level exit that transitions to an overworld map, use a script that defines a couple of locations on the map (level entrances) that the player can travel to in this manner:

This script should typically only be executed once, hence the "End" command that runs last.

Predefined script vars

There are a number of predefined script vars that begin with an underscore. You may select these in variable commands to examine or set certain game states.

• _MyWeapon - Sets the weapon wielded by the NPC.
• _MyColor - Additional tint applied to the character. When the value is -1 (default) no color is applied, otherwise the format is a 6-digit number RRGGBB, where RR is the value for Red tint, GG for Green and BB for Blue. Value of 50 for given color is normal, lesser than 50 will reduce the color, larger than 50 will add the color. Some examples:
  • 505050 - No color change
  • FFFFFF - Twice as bright
  • 005000 - Red and green will be removed
  • FF5050 - WIll be more red than before
• _MyHue - a number between 0 and 6000, inclusive. If it is set to a non-zero value, it will change the base color of the NPC's image. At a value of 1, the image is shifted to red. Increasing values will shift to orange, yellow, blue, green, indigo and violet, before cyling back to red as the value approaches 6000. Black, white and greys in the character's image are not affected by this change.
• _MySaturation - a number between 0 and 1000, inclusive. If it is set to a non-zero value, it will change the base colors of the NPC's image. Lower values make the colors less intense, while higher values make them more intense.
• _MyX and _MyY - X and Y position of the NPC. Please keep in mind that the change is instanteous, if you need to modify the position in both axes use 'Teleport to' instead, otherwise you risk creating problematic situation when the NPC teleports first in one axis and then in the other.
• _MyO - NPC's current orientation.
• _MyName - Name of this NPC. Used for right-click inspecting and for speech log.
• _MyScript* - Variables used to inject dynamic values into other scripting commands. See this section for explanation on how to use them.
• _X and _Y - X and Y position of the Player. Can cause the same potential problems as _MyX and _MyY, so use 'Teleport player to' wheen you need to teleport along two axes.
• _O - Player's current orientation.
• _PlayerWeapon - Can be used to check the player's base weapon, or to indefinitely change their weapon in the same manner as the Set player weapon command. This value can also be set to -2 to disable the player's weapon, and to -1 to enable it.
• _PlayerLocalWeapon - Can be used to check the weapon currently being used by the player, or to set their current weapon for the duration of the room. This value can also be set to -2 to disarm the player, and to -1 to rearm them, as if touching a Disarm token.
• _RoomImageX and _RoomImageY - Offset of the custom room image in tiles.
• _OverheadImageX and _OverheadImageY - Offset of the custom overhead image in tiles.
• _ThreatClock - See this section.
• _LevelName - Read only! Gets the name of the level.
• _RoomX and _RoomY - Read only! Gets the position of the current room in the level.
• _Input and _InputDirection - Read only! Gets the command value of the player's last input and the move direction of that input respectively. For inputs that do not move the player, such as rotations, a value of 4 is returned for the input direction.
• _PlayerLight - See this section
• _PlayerLightType - See this section
• _ReturnX and _ReturnY - Used by other commands to return values for later use, eg. Get Natural Target. Otherwise can be used for temporary storing information.
• _SpawnCycle - Read only! Gets the current turn in the spawn cycle, between 0 and 29.
• _SpawnCycleFast - Read only! Gets the current turn in the spawn cycle, between 0 and 59. Even values correspond to normal turns, while odd values correspond 'half turns' where the player is moving with a speed potion.
• _Combo - Read only! Gets the current "combo value", the number of monsters the player has killed in a continuous run of turns.
• _RoomWeather - See this section
• _RoomDarkness - Controls the lighting level of a room. Can be set between 0 (no darkness) to 6 (the highest level of darkness) inclusive. If the Skip light crossfading setting is not enabled, the room will perform a fade from the old light level to the new light level.
• _RoomFog - Controls the fog height in the room. Can be set between 0 and 3 inclusive.
• _RoomSnow - Controls the rate of snowfall. Can be set between 0 and 9 inclusive. At zero, no snow falls.
• _RoomRain - Controls the rate of rainfall. Can be set between 0 and 19 inclusive. At zero, no rain falls.

Player light vars

Threat clock display modes

Room weather vars

_RoomWeather affects the weather settings in a room. It is bit map value of the settings, meaning it can contain multiple values created by just adding them. The supported values are:
1 (0x001) - Outside
2 (0x002) - Lightning
4 (0x004) - Clouds overhead
8 (0x008) - Cloud shadows
16 (0x010) - Skip light crossfade

List of player command input variables

• MoveNorthwest
• MoveNorth
• MoveNortheast
• MoveWest
• Wait
• MoveEast
• MoveSouthwest
• MoveSouth
• MoveSoutheast
• SwingClockwise
• SwingCounterclockwise
• Restart
• Undo
• Battle
• UseCommand
• UseCommandTwo
• UseCommandThree
• CloneSwitch

Image overlay commands

Movement types